ci(registry): publish the MCP registry listing on its own when it changes (APP-14167) - #70

Ticket: APP-14167. Dave Oster asked for this in their Alma chat.

Why

The official MCP Registry only updated when someone ran Publish MCP registry metadata by hand. Nobody ran it from July until November 4, 2026, so the registry showed an old description for months. The listing also lives in two places, server.json here and the copy mcp.dealmachine.com serves, and those have drifted before.

What changes

• The workflow runs on its own: after a master push that changes server.json (or the workflow or its script), and every three hours as a catch-up. The manual button stays for retries. It keeps the PRODUCTION_DEPLOY_ENABLED gate that npm publication uses, and master only moves through an approved release.
• It publishes only real listing changes. scripts/mcp-registry-sync.mjs plan compares server.json with the live server's /.well-known/mcp.json and with the versions the registry already has:
  • new version that the live server already serves: publish, then verify waits until the registry lists it as latest;
  • registry already has that exact version: pass, publish nothing;
  • server.json ahead of the live server: pass with a note, and a later scheduled run publishes once the MCP release lands;
  • wording changed under a published version number, the live server is newer, or same version with different wording: fail with a message that says which copy to update, publish nothing.
• Bug fixes and tool description changes never trigger a publish, because the registry stores only the name, title, description, version, repository and address.
• docs/releases.md gets an MCP registry listing section, and the README links to it.

Decisions

• When the copies disagree, the check fails instead of picking one, because published registry versions can't be changed or pulled back.
• I didn't change the MCP server repository. Its listing copy stays where it is, and the live comparison catches drift between the two copies.
• I chose a three-hour schedule over hooking into the MCP production deploy. The deploy runs from Alma's command, so a hook there would cross repositories. The schedule only costs a few public reads per run.

Proof

• tests/mcpRegistrySync.test.ts: eleven cases: each decision, both directions of a reworded published version, key order, a lower version, the copy shipped today, and starting the script through a linked folder (that last one failed before the fix: the script exited successfully without doing anything).
• npm run check: 129 tests pass, and the artifact check passes.
• Live, read-only: plan against the real registry and mcp.dealmachine.com answers "already lists version 0.3.1, nothing to publish". verify confirms 0.3.1 is the latest. Nothing was published.
• Not yet proved: a real publish from the new workflow. That happens the next time the listing version changes. The first master push of this change runs the check, which should skip.

🤖 Generated with Claude Code